Shipment Dispatch

When an order matched to a shipment order from your integration is picked, Pio will send a shipment dispatch request to your integration.

The request is sent to the dispatch_url specified when the order channel was created.

See the Shipment Dispatch request example for details about the request.

The request uses the webhook (v2) structure. i.e. it contains a signature for verification, expects a 2XX response to indicate it was received successfully, and is expected that the dispatch is processed outside of the http request context. As with webhooks it is also possible that the request may be sent multiple times. Because of this, it is important that you pay attention to the shipment_id in the payload, and avoid reprocessing the same request multiple times.

Once the shipment dispatch has been processed, Pio expects a POST request sent to the dispatch response endpoint with the results of the shipment dispatch.

The dispatch response payload must include the success field (either true or false). If there was a problem with dispatching the shipment, the success field should be set to false and an error field must be included. The error message should be something human readable as it will be shown to the users. If the shipment was dispatched successfully, success should be true, and the label field should be provided as a base64 encoded pdf of the shipping label.

If an error was returned, another dispatch request may be made for the same order (e.g. the user may change the selected shipping rate and try again), but this will have a different shipment_id to distinguish it from previous attempts.